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APPLICATION PROGRAM INTERFACE FOR 
MESSAGE-ROUTING AND MANAGEMENT SYSTEM 

FIELD OF THE INVENTION 

The present invention relates to communication services, and in particular to 
delivery of messages to selected recipients through one or more specified communica- 
tion modes. 


BACKGROUND OF THE INVENTION 

Thanks to improvements in technology and widespread consumer interest, once- 
exotic forms of communication have become commonplace, and today the average 
consumer has access to a broad array of communications services. The Internet and 
wireless telephony, once the preserve of an elite few, now routinely supplement tradi- 
tional telephone services and are frequently supplied by the same carriers. Even inex- 
pensive home computers now include facsimile capability. Businesses employing mo- 
bile employees can furnish them with economical pagers that incorporate advanced 
features, such as text transmission and Internet access. 

The sheer proliferation of communication options, while greatly improving ac- 
cess and convenience, has engendered problems as well. The existence of a communi- 
cation channel does not ensure that the recipient of a message will be "listening" to that 
particular channel at a given time, yet the sender of a message has no way to know this. 
Indeed, more channels of communication traffic mean more demands on the attentions 
of potential recipients, who, feeling besieged by the assault of e-mail, voice mail, 
pages, etc., may simply inactivate some communication devices at different times. 
Message senders, therefore, are faced with the choice of risking non-delivery of their 
messages, or painstakingly re-transmitting a message on every possible mode of com- 
munication modality. 
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It may also be difficult to transmit the same message to multiple recipients. 
While a single e-mail message, sent once, can reach an unlimited number of destina- 
tions, phone messages must be repeated for each call. Moreover, different recipients 
may have access to different types of communication channels; perhaps some recipients 
5 can be reached efficiently only by e-mail, others by fax, and still others by page. 

The integration of communication input devices also raises the prospect of mes- 
sages having multiple forms of content. Today, a single message may include input 
from a variety of sources (e.g., voice and text); transmitting such a message by tradi- 
tional means may be quite cumbersome, involving multiple separate transmissions that 
must be coordinated or difficult "packaging" of the different inputs into a single mes- 
sage. 

U.S. Serial No. 09/496,170, filed on February 1, 2000 and entitled Multi-Mode 
Message Routing and Management (the entire disclosure of which is hereby incorpo- 
rated by reference) addresses these difficulties and discloses, inter alia, a facility for 
transmission of messages composed on one or more input devices to a single or multi- 
ple recipients by means of one or plural communication modalities. Such communica- 
tion modalities may include, for example, conventional or wireless telephone, facsimile 
transmission, pager, e-mail, postal mail or courier. Thus, a message may be directed to 
a single recipient via multiple modalities, such as e-mail and fax, in order to ensure the 
earliest possible receipt of the message; or may be directed to multiple recipients by a 
single modality or by different modalities (e.g., some recipients receive the message by 
e-mail, others by fax, others by phone). The facility may be configured to respond to 
defined "escalation" rules that specify conditions under which different delivery mo- 
dalities may be sequentially employed. For example, the rules may specify that if there 
is no response to an e-mailed question within an hour, the recipient is to be telephoned. 
Moreover, in addition to alternative transmission modalities, the escalation rules may 
specify alternative recipients (as well as alternative modalities for those recipients). 
The escalation rules may also specify default contact methods, which may apply to spe- 
cific individuals or to lists of recipients. 

The invention disclosed in the 5 170 application may include functionality for 
determining whether a message has been received (e.g., telephone and e-mail polling), 
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as well as automatic sender notification upon confirmation of receipt. Moreover, in 
addition to monitoring messages in order to confirm their receipt, the invention may 
facilitate recipients' responses. In this way, the invention can orchestrate multi- 
question surveys utilizing multiple communication modes; for example, individuals 
contacted directly can respond immediately, while others can respond later in accor- 
dance with instructions delivered to them — e.g., via a web site or by calling a toll-free 
number. 

The invention disclosed in the '170 application supports messages having em- 
bedded questions that call for response by the recipient. Such responses, when re- 
ceived, may be communicated to the message sender and/or accumulated. 

Also facilitated by the invention disclosed in the '170 is scheduling of message 
delivery, on a mode-by-mode basis where appropriate. Scheduling may include deliv- 
ery at a particular time or within a designated time window, or may involve preventing 
delivery during specified "black-out" periods. In some embodiments, scheduling may 
be automatic and based on considerations such as the recipient's time zone and the 
form of communication (e.g., to avoid awakening the recipient by telephone). 

However, the ' 1 70 application contemplates a system in which customers' cli- 
ent computers communicate via the World Wide Web (the "web") with a server im- 
plementing the foregoing functions. In other words, the interaction is essentially man- 
ual and stepwise in nature, with customers selecting options and indicating preferences 
in an interactive session. This model is generally unsuited to business applications re- 
quiring more automated, high-volume access to messaging functions. 

DESCRIPTION OF THE INVENTION 
Brief Summary of the Invention 

The present invention provides an application program interface (API) facili- 
tating interaction, generally (although not necessarily) via the Internet, with a message- 
handling facility such as that disclosed in the '170 application. In accordance with the 
invention, application programmers utilize a markup language (preferably XML- 
derived) to configure applications for compatibility and communication with the mes- 
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sage-handling facility. The API is capable of processing high-volume requests for 
message routing, status information, and various other functions on an automated basis, 
enabling businesses to make routine use of these functions. 

Indeed, the range of business-to-business and business-to-consumer organiza- 
5 tions that can benefit from flexible messaging services is virtually limitless. For exam- 
ple, an airline may obtain contact information from passengers when tickets are pur- 
chased. Should a flight be delayed or cancelled, the airline can generate a single notifi- 
cation for transmission to all passengers via the messaging facility; as the flight time 
approaches, efforts to reach passengers not yet contacted can be intensified according 
to defined escalation rules. Similarly, a club or other organization can send out notices 
of meetings, receive confirmations and preferences from members, and alert them to 
changes using the messaging facility by means of the API. The message need be writ- 
ten and transmitted by the organization only once; all remaining operations, from bulk 
re-transmission to collecting and organizing responses, are performed automatically. 

In accordance with the invention, a message server comprising a plurality of 
modalities for transmitting messages is associated with an API. An application, typi- 
cally implemented on a remote server, is configured to receive a message and a desig- 
nation of one or more transmission modalities, and is further adapted for interaction 
with the API. The API comprises stored instructions supporting the interaction. Upon 
receiving the message and the designation from the application server, the API causes 
the message server to transmit the message according to the designation. 

BRIEF DESCRIPTION OF THE DRAWINGS 

The foregoing discussion will be understood more readily from the following 
detailed description of the invention, when taken in conjunction with the accompanying 
drawings, in which: 

FIG. 1 schematically represents the environment of the invention; and 
FIG. 2 schematically illustrates the components of the API and its mode of in- 
teraction. 
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DETAILED DESCRIPTION PREFERRED EMBODIMENTS 

1 . Technical Context 

The functions of the messaging system are implemented by a server 125, which 
may be realized as a single workstation or as a network of server computers, depending 
on the activity level and included functionality. For explanatory purposes, server 125 is 
represented as a single machine that includes a network interface 127 continuously 
connected to the Internet. Network interface 127 and the other internal components of 
server 125 intercommunicate over a main bidirectional bus 130 (which may be a physi- 
cal bus in a single hardware device, or can instead represent a network such as a LAN 
or a WAN). The main sequence of instructions effectuating the functions of server 125 
1 and facilitating interaction among customers, server 125, the Internet, and other modes 
of communication reside on a mass storage device (such as a hard disk or optical stor- 
age unit) 132 as well as in a main system memory 134 during operation. Execution of 
these instructions and effectuation of the functions of server 125 is accomplished by a 
central-processing unit ("CPU") 136. 

A group of functional modules that control the operation of CPU 136 and per- 
form the operations of server 125 is shown conceptually as located in system memory 
134; once again, however, it should be stressed that this organization is for explanatory 
purposes. The various modules and servers may indeed be implemented as active proc- 
esses running on a single machine, but functionality may instead be distributed among 
multiple machines (or processors within a single machine), once again depending on 
the activity level and included capabilities. 

An operating system 140 directs the execution of low-level, basic system func- 
tions such as memory allocation, file management, and operation of mass storage de- 
vices 132. At a higher level, a control block 142, implemented as a series of stored in- 
structions, manages interaction among the various functional components of the server 
and ensures proper routing of data thereamong. 

Although server 125 may be capable of communicating directly with customers 
by means of the web and electronic mail, as explained in the '170 application, the pres- 
ent application is concerned primarily with hardware-to-hardware communications. 
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Accordingly, an API 145 receives and processes communications from external 
sources, and transmits proper responses to those sources, via network interface 127. 
API 145 represents a programmatic interface for direct connection to appropriately con- 
figured third-party applications. The pattern of interaction with the external source, 
including the content of transmissions thereto, is handled by a transaction server 1 50. 
Transaction server 1 50 has access to various databases, collectively indicated at 152; 
these databases, discussed in greater detail below, are ordinarily stored on devices 132 
and accessed as necessary. Depending on the requests received by API 145, transaction 
server 1 50 causes messages to be assembled and transmitted to designated contacts, and 
retrieves and assembles information for transmission to outside inquiries. Credit-card 
validation and billing for services are handled by a billing server 160. 

The various functions performed by server 125, which result in different pat- 
terns of interaction with customers, will now be described. 

1.1 Media Conversion and Basic Message Transmission 

A series of media servers, collectively indicated at 175, represent the interface 
servers that format messages for transmission; these messages may be in the form of 
voice, text (for transmission by e-mail, web or postal mail), or other desired format. 
Messages and media designations are received from remote applications via API 145, 
and once transaction server 150 has received sufficient commands and content to fully 
specify a message (i.e., the message body, the recipient(s), desired delivery methods, 
and message options such as delivery scheduling and/or escalation rules), a message 
"job" is created and stored in a database 152. The job is passed to a job queue server 
165, which is responsible for implementing and scheduling all message jobs. 

At this point, the message remains in the format in which it was generated. As 
noted previously, however, server 125 is capable of receiving messages, via the inter- 
face servers, in one format and transmitting them in a different, customer-selected for- 
mat. The functions of media conversion and message assembly are performed by a se- 
ries of message delivery servers, collectively illustrated at 167, dedicated thereto. The 
appropriate message delivery server 167 converts messages to the specified format and 
causes their transmission, via the designated communication medium, by means of a 
corresponding device driver selected from among a suite of drivers. The drivers oper- 
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ate a series of transmission devices, which include network interface 127 for e-mail 
and/or web-based message delivery; a telephone interface 170 for message transmission 
by telephone, facsimile, pager, or handheld wireless device (although it should be noted 
that pager and wireless transmission can occur through network interface 1 27); and a 
document-generation module 172 for message transmission by postal mail or overnight 
courier. 

The timing of message transmission is governed by job queue server 165. In re- 
sponse to the customer's authorization to send a message, job queue server 165 triggers 
the conversion and transmission operations just discussed. Job queue server 165 also 
contains (or, as shown for illustrative purposes, communicates with) a scheduling mod- 
ule 180, which can orchestrate transmission of messages at customer-specified times 
based on the computer's internal clock. 

Server block 1 65 may contain a text-to-speech conversion module, enabling 
customer-provided text to be transmitted by voice to the recipient by means of tele- 
phone interface 170. Conversely, telephony server 175 may be configured to respond 
to spoken customer commands, allowing the customer to compose and address a mes- 
sage by telephone (i.e., by communicating with server 125 by means of telephone inter- 
face 170). 

In still more complex operational modes, server 125 may facilitate catenation of 
message — either as separate segments of the same format, or as segments encoded in 
different formats. In the case of audio messages, for example, a message delivery 
server 167 may append an audio "header" (typically a so-called "professional prompt") 
and a "trailer" to the customer's message. Thus, when the recipient answers the tele- 
phone, the header portion of the message may tell him that he is about to receive a mes- 
sage from the customer, and the trailer portion may facilitate response (as explained in 
further detail below). 

1*2 Confirming Message Receipt 

Any of a variety of techniques can be used to assess whether and when a mes- 
sage is received. Many e-mail systems natively support receipt confirmation. Alterna- 
tively, a URL can be embedded in the message; when the recipient receives the e-mail 
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and clicks on this URL, receipt is automatically recorded. Moreover, the URL- 
specified web page may contain questions inviting response by the recipient, who 
thereupon transmits the web page back to server 125. 

Hard-copy deliveries can be tracked through the courier or by means of a fol- 
low-up telephone call to the recipient, while for telephone messages, the recipient can 
be asked to press a number to confirm receipt. In the context of telephone messages, it 
may be useful to detect whether a person or an answering machine has answered the 
phone. This determination can be used, for example, to select a proper audio header or 
even to choose between alternative messages, which may differ depending whether the 
message is delivered to the recipient or a recording device; an answering machine, ob- 
viously, would not be asked to press a number to confirm receipt, nor would delivery 
typically be confirmed to the sender if the message was left on an answering machine. 
To implement answer detection, telephony server 147 is programmed to monitor the 
level of noise on the line once a connection is established, distinguishing between a 
"silence" noise level and a "speech" level. If an individual answers, he or she will typi- 
cally issue a short greeting; that is, the signal pattern of a human answer is a short 
speech signal followed by silence. An answering machine, by contrast, will generally 
issue a long greeting ("Hello, you have reached the Smiths . . Based on the ob- 
served lengths of a sustained speech signal and an ensuing silence, telephony server 
147 forms an initial guess as to whether a person or a machine has answered. If a per- 
son is guessed, telephony server 147 will play the audio header that prompts the an- 
swerer to press a touch-tone key, and if the proper touch-tone pulse is not detected, 
server 147 may revise its guess and assume that it is communicating with an answering 
machine. 

1.3 Message Scheduling 

It may not be appropriate to transmit messages by certain modes during par- 
ticular time periods at the recipient's location. These "blackout" time periods may be 
established automatically by server 125, or may be designated by the customer or the 
recipient. Via API 145, an external application may indicate blackout time periods for 
a particular message, or may permanently designate such periods for particular contacts 
(and particular communication modalities). Most commonly, permanently designated 
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blackout periods are used to prevent messages from being sent by telephone or pager 
during times when the recipient is generally likely to be asleep or away from the com- 
munication modality. Message-specific blackout periods may be utilized by message 
senders familiar with the recipient's immediate schedule, or who do not wish to perma- 
nently establish blackout periods. 

Conversely, the external source may specify particular allowed time windows 
within which a message must be delivered. Once again, these may be established per- 
manently for particular contacts or "on the fly" for specific messages. 

Time-zone scheduling may be employed automatically. For example, if the 
customer authorizes immediate message delivery at a time that would be late at night 
where the recipient is located, or schedules message delivery for such a time, transac- 
tion server 150 may cause the customer to be prompted with this information and asked 
to confirm or reschedule delivery. 

1.4 Escalation 

Rather than send a message to a prospective recipient redundantly via multiple 
communication modalities, transaction server 150 may be configured to allow the 
specification of escalation rules for sequential transmission as necessary. The external 
application selects a plurality of communication modalities and/or contacts, and criteria 
in the form of rules governing their use. Typically, an escalation rule will specify re- 
sort to a different communication modality (or a different recipient) if delivery of the 
message is not confirmed by a specified time, or within a specified period, using the 
current communication modality. 

Like scheduling restrictions, escalation rules may be defined permanently for a 
contact (and stored, along with "address book" information pertaining to that contact, in 
database 1 52b) or may instead be defined for a particular message. Default message 
modalities and permanent escalation rules are particularly useful in the context of dis- 
tribution lists, since the external application can simply enter a message and leave it to 
server 125 to deliver it to every person on a selected distribution list in accordance with 
each contact's escalation rules. On the other hand, message-specific escalation rules 
may be designated for particular messages transmitted to API 145. 
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To implement the escalation rules, the time period specified in a rule relevant to 
the initial message transmission is sent to scheduler 1 80. At the end of that time period 
following transmission, transaction server 150 determines whether the message has 
been received in the manner described above. If not, the escalation rule (defined in 
database 1 52b or in the transaction record for the particular message) is executed, and 
the message re-transmitted by a different modality. If further escalation rules remain 
for the message, the appropriate time period is once again provided to scheduler 1 80, 
and the flow sequence repeated. 

2. An Exemplary Application Program Interface 

With reference to FIGS. 1 and 2, external sources such as a server 190 generate 
requests for messaging functions and status information, and transmit these to server 
125 via a computer network, such as the Internet, for processing. FIG. 2 illustrates in 
greater detail the role and basic components of API 145. Requests are actually gener- 
ated by an application 210 running as an active process on server 190. Application 210 
formats these requests in the syntax allowed by API 145. Requests received by API 
145 from application 210 are analyzed by a parser 210, which interprets the request and 
causes the various server modules of server 125 to take appropriate action. The server 
modules may generate direct responses to the requests or provide status information for 
transmission to application 210. A converter 220 places such information into state- 
ments conforming to the API syntax prior to transmission. 

Preferably, the API syntax conforms to the conventions of XML, using t4 tags" to 
characterize elements such as statements and field data. A tag surrounds the relevant 
element(s), beginning with a string of the form <tagname> and ending with 
</tagname>. Thus, parser 215 can be (or be based on) a conventional XML parser. 

The contents of a communication to or from API 145 take the form of a "docu- 
ment," which contains an identifying tag and either a "Request" (for documents gener- 
ated by application 210) or a "Response" (for documents that API 145 returns to appli- 
cations 210). Document elements are hierarchically organized into objects. Each ob- 
ject specifies the contents of fields associated with the object, and may also contain one 
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or more nested, hierarchically inferior objects; this structure maintains the organization 
. of information, facilitates movement of information in meaningful packages, and al- 
lows for re-use of information without explicit repetition. 

At the highest hierarchical level, "Super Objects" define the communication as 
5 a Request or a Response, and contain one or more "Major Objects." The Major Objects 
specify key functional elements of messaging activities, defining the relevant user ac- 
counts and the nature of the desired message functions, and may contain sub-objects 
and/or entries for various fields within the Major Objects. Fields contain information, 
such as character strings or numbers, relevant to the objects containing them. 

10 The overall organization of a preferred implementation of API 145 appears in 

summary form below; following the summary, the various objects and fields are de- 
scribed in greater detail. It should be understood that this API is illustrative only. 


Table 1 


15 


Basic API Organization 


I. 


Super Objects: contain required fields and one or more major objects 


A. 


Request (fields:) 


20 


i) 
ii) 
iii) 
iv) 

v) 
vi) 


UserName 

Password 

Domain 

OEMId 

OEMPassword 

RequestType 


25 


B. 


Response: same fields/objects as request + errors, warnings 


II. 


Major Objects: required elements of documents, may contain sub- 


objects and fields 


30 
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Member (fields:) 

i) Command 

ii) Id 

iii) FirstName 

iv) LastName 

v) Company 

vi) UserName 

vii) Password 

viii) AllowNotices 

ix) Dialinld 

x) Dial in Password 


Member (subobjects:) 

i) Contact Method 

ii) Billing (fields: Id; Billing Plan; CurrentBalance) 

iii) Credit Card (fields you'd expect) 

Contact (subobjects:) 

i) Contact Method (fields:) 


a. 

Id 

b. 

Transport 

c. 

Qualifier 

d. 

Ordinal 

e. 

PhoneNum, FaxNum, PagerNum 

f. 

Access Code 

g- 

Email Address 

h. 

Street 1 

i. 

Street2 

j- 

Suite 

k. 

City 

1. 

State 

m. 

Zip 

n. 

Country 

Contact MethodRef (fields:) 

a. 

Id 

b. 

FirstName, LastName, Company 

c. 

Transport, Qualifier, Ordinal 

d. 

AllowMultipIe 
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Contact (fields:) 

i) Command 

ii) Id 

iii) Prefix (optional) 

iv) First Name, Middle Name, Last Name 

v) Company (optional) 

vi) Title (optional) 


C. Distribution List (fields:) 

i. Command (create, replace, append, delete, remove) 

ii. Name 

iii. Description 

iv. Id 


D. Job (fields:) 

i. Id 

ii. Charges 


Job (subobjects:) 

i. Message (fields:) 

A. Subject 

B. Template (optional) 

C. Id 

D. Date 


Message (subobjects:) 

A. MessageArg Objects: series of Name/Value tags 


1) 

SENDER 

2) 

BODY 

3) 

ASK YESNO QUESTION 

4) 

QUESTION TO ASK 

5) 

EMAIL ADDR 


DeliveryTime Objects 
DeliveryTimeModifier Objects 
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ii. Contact (to specify one-time recipient of message) 

iii. Delivery Request (elements:) 


A. DeliveryOptions field (in) 

B. Contact MethodRef sub-object 


Delivery Request (returned elements:) 

A. ContactMethod 

B. Contact 

C. Delivery (fields:) 


1) Id 

2) Timestamp 

3) Duration 

4) Status (Not Sent, Sent, Failed, Cancelled, Cancel 
Pending) 

5) Details (Bad Address, Delivery Address is unreach- 
able,!^ Answer, Busy, Answering Machine (assumed), 
Answering Machine, Maximum Delivery Attempts Ex- 
ceeded, Acknowledged, Modem, Hangup, Callback 
Later, Internal Error 

6) Size 

7) Cost 


DeliveryRequest fields (out) 

1) Id 

2) EstDuration 

3) EstSize 

4) Status 

5) Details 

6) Completed 


Range (fields:) 

i. Object (i.e., type of object trying to look up) 

ii. Type 

iii. Start 

iv. End 


WO 01/69385 


PCT/US01/07727 


15 

Every transmission to API 145 requires a Request, which will generate a Re- 
sponse from API 145 (and the server modules with which it functions). The Request 
must identify one or more valid "members" by means of UserNames. A request con- 
tains the following required fields: 

5 Table 2: Request Fields 



Descripfion : : ■-•ss5. : :- : 

In/Oiit:- 

Allowed Values; 5 

Example ■ :'v^* : >: ; ■. .-j 


fcpgin name tKgfrtf ^ ^ 


Siring:^-.::;- ■ ■ : - 

<Use^ame^taliiHW, :;; - 

Passwords ^ 

Password fdrtfe;mer^ 

In - : fSS; 

Stnjig •: 

<Password>abcl23:* : ^"4"-. : 

Domaintii^i^ 

Idem^fiefe(ge^^ theTcwn^-;^; 
panydi^OT^ 



<Ooiftlin§I^^^ 


the domain lD;(identifies cSffipa5yIor:;iS 




OE^ffa^sjybrd; 




<GEMPassw6rd>^-;: 1 

g^ps^wc|%i— ; * 1 

tosses 

R^uesjts;6n^^^ 

Validate (Qie^k aiK#^e^l^:and^^| 
Commit: (PutMeVdbcffie 

lip 

raUdatei ; '4-v; : "".-*7 

5R^if(^tTyi^yaliSafe •] 


(In this and other tables, the In/Out column indicates whether the field is used in 
a Request (in), in a corresponding Response (out), or in both.) 

10 In addition to fields, the Request will generally contain one or more Major Ob- 

jects. Typical actions include: send a message to specified recipients; add/edit/delete 
member, distribution list, contact information; look up the status of a job; send a billing 
inquiry. The following represents a typical Request (with the Contact Object, discussed 
in greater detail below, indicated but not actually specified): 
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<RequestxUserName>RalphW</UserName> 
<Password>abc 1 23</Password> 
<Domain>POETS</Domain> 
<OEMld>OEMId</OEMId> 
5 <OEMPassword>OEMPassword</OEMPassword> 
<RequestType>vaIidate</RequestType> 
[Contact Object] 
</Request> 

The Response is generally returned with the same objects that were included in 
the Request; if, however, the Request asks for information (e.g., a request for message 
status or for billing information), some objects or fields may be added or changed. In 
addition, the Response will contain Errors and Warnings fields as appropriate: 




In/Out?- 




Seftplthemumber ofielroireidi^oY-J 
ejred'wii^ 

objects inclucj feict iif the|Requcstlfe-: j 

■..;r7;:=;r<-,; 

iJnsi^edi'^^j 

<EirbW3'^TOrs> ' ' " v^ 1 !^-?? 

^arningsg; 

Set M tfie :hum^r : P^y^TP ^g^® ^ 

legfj|e^^ 

profcelsihtfi^^ 

eluded^ withe Request^? , 


Integer^ " 

• r.v'-. - • .^.--si> . -:, ; zgfM : : . ~v, -x ~A ■ i 


Table 3: Errors and Warnings (Response Fields) 

Errors and Warnings are described in greater detail below. 

The following represents a typical Response (with the Contact Object once 
again indicated but not actually specified): 

<Response> 
<UserName>Ralph W</U serName> 
<Password>abcl 23</Password> 
<Domain>Poets, Inc.</Domain> 
<OEMId> OEMId</OEMId> 
<OEMPassword> OEMPassword</OEMPassword> 
<ResponseType>validate</ResponseType> 
<Errors>2</Errors> 
<Warnings>0</Warnings> 
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[Contact Object ] 
</Response> 

Requests and Responses specify one or more Major Objects as follows: 


Major Object 

Description 

Member 

User-level login that identifies a user account (end user or member) 

Contact 

Person or organization to which a message may be sent 

Distribution List 

A group of contact methods (for example, phone number, pager number, email 
address) to which a message may be sent 

Job 

Message to one or more contacts using one or more contact methods 

Range 

Used to look up other objects based on specific search criteria; for example, to 
look up a job by Id, or jobs sent on a certain date, or all contacts from the same 
organization 


5 Table 4: Major Objects 

Each Major Object contains zero or more fields and sub-objects, which may 
themselves contain additional sub-objects and/or fields. The various Major Objects 
will now be described in detail. 

Major Objects — Member : generally an end user of the messaging service. 

io Major Objects — Member : — Fields: The Member object has the following fields: 





ValueiJffe-i 



Update"^ 

Remove ^m6s^MeAWT:bbE^i 

r^:':-.r^'V'.-' ; ; 

ilil* 

^omffiluiQ^ fjg^ 

mzrrm .1.3; 

i^dpgejp^^^ 
Response^ 

MembeF:objec1|^^-iii^ii?^^:'.^ 


SjftRalili^ 

menc?iSS- 


FirstNarl^ 



StringiWith"? 

charaVter^l 
limit; 

<®rStNa%e>Yfrimi^ SsSfii'i 


llierfnembeWs-laisitmamejf^ 


iltlf 

character^ 

^astNMeS\^if>^^ 
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Company 
(Optional) - 

T&inemte^s cpnipahyaftiliSion 

1 ■ ' - :■ * ( ' .- 

n~- *••--. " £3* • ■■V , *'^Vi'.r-ii:i;.^:;iv!sr-- ' - A* " ■• 


String with 

a32 r . -v 
character 
limit i: 

<C6mpany>Hogafoi Press^Gbni pany> ^ 

tjfserWmne^.; 

The memoer's I6gin; iriust be r : 
unique within i th&.domaiiF • ^fT - ^; 

§s- If 

String with 

character^ 
limit, ^ 

^Use^am^VirginiaW^^ 

Password J; - 

Thejinemb^r's secret paskwoniS.:. i 


StrihgwitK, 

a : 3?^ ; 1, 
chfeerl 

. 17 V.-.-.*-.- — 

liriiii v ; f - 

Passwprd>abc 1 23^as§word§£: '^J'K^r^t- 

g-. v- - -^ Ify^; ;V - HrfSil- . : f jVtS±\ ; * ' 

AlIowNotices".; 

teresied'i^ 

ociibmailings sp^ificiothis-do^v 

nia^'^^ -life ^r^W"- : "^ 

Inn - fi'i 

a Wow): 
otherwise/^: 

<AiIpwNotice^trMe '--ir*§^^ ■ .§K*-f 

<MHow>^ices>S -T'ts^&y^i'-Z ;.. 

Dailihld 

ThiCisa >£jiy tforjthe member/|g ; ; J 
identir^t^^ 

a !§>ice' ir^on^(aut6hia^^ 
to^Kfe 


strigg;. ; ' 


DiajinPassri;:- 

Sejfoes;as$ PIl*|oK the r^ice ng^H 



<Pj^^a^6rd^l 234 f 

^iyinPa^word|^;;|^®^ 


Table 5: Member Major Object Fields 

Major Objects — Member — Sub-objects : In addition, the Member object con- 
tains the following required sub-objects: 

5 Major Objects — Member — Sub-objects — Contact Method: specifies communi- 

cation mode (e-mail, telephone, etc.) and contact information (e-mail address, tele- 
phone number, etc.) specific thereto. Contact Method sub-objects are further described 
below in connection with the Contact Major Object. 

Major Objects — Member — Sub-objects — Billing: specifies the billing plan and 
10 details necessary to bill the member (such as a credit-card number). The object also 
describes the current account status. The following table sets for the required fields for 
the billing sub-object: 
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Fields - 

Descripti A ^ :' : H 

In/Out 

Allowed 
Values 

;; T ' r Example; " i 



Out;.; - : . 


<:Id>kl23!bj4</Id> : =k : - V.:.*.. ~j ^.M 

BijlingPlin^:, 

ndicates whicfrplan the member is . 
^sinfe^^-you-^p^paid^both 
usinppdjt card)L ; 

?; re--- 



11 ill 

|t^n«CeJd^S:doU^ # j ™; :■ 




Table 6 
Member Major Object 
Billing Sub-object 

The billing sub-object, in turn, contains a Credit Card sub-object, the fields for 
which are set forth in the following table: 
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State 

State of billing 
address for this 
card 

in . ... 

Use two- 
letter state- 
abbrevia- 
tion i 

<State?>eft<^Stite> • -W^ : . 


Zip. codjejiirthe;, 
U§; ppSa£cwie 
outside^ . :V;/I, 

-J 

Zip iwKies : 
Qanbe^i- 
fer^^^r: 
nine dibits; 
hyphentijl^ 

^i^.9p2;10-1234*</Z.^ : ^-yi- : ; ^v;£\\; ^ 




All e ■ a* c Am (/ i j 

gQimtr^; V 
name 




Table 7 
Member Major Object 
Billing Sub-object 
s Credit Card Sub-object 

The following is an example of entire Member Object: 

<Member> 

<Command>create</Command> 

<FirstName>Ralph</FirstName> 
1 0 <LastName>Emerson</LastName> 

<Company>Poets R Us</Company> 

<UserName>RWE</UserName> 

<Password>MyPassword</Password> 

<DialinId> 1 2345</DialinId> 
1 5 <DialinPassword> 1 23 45<^DialinPassword> 


<ContactMethod> 
<Transport>email</Transport> 
<Qualifier>none</Qualifier> 
20 <EniailAddress>ralph@Poets.com</EmailAddress> 
</ContactMethod> 

<ContactMethod> 

<Transport>phone</Transport> 
25 <Qualifier>office</Qualifier> 

<Ordinal>0<Ordinal/OrdinaI> 

<PhoneNum>617- 1 23-45 67</PhoneNum> 
</ContactMethod> 


30 <Billing> 

<BilIingPlan>kkk33kkkk<BiIlingPlan> 
<CurrentBalance> 1 .00<CurrentBaIance> 
<CreditCard> 

<FirstName>RaIph</FirstName> 
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<M iddleName> WaIdo</MiddleName> 
<LastName>Emerson</LastNaine> 
<CreditCardType>Master 
Card</CreditCardType> 
5 <CreditCardNumber>5123 123412341233</CreditCardNumber> 

<ExpirationYear>2001</ExpirationYear> 
<ExpirationMonth>8</ExpirationMonth> 
<StreetAddress 1 > 1 3 1 3 Mockingbird 
Lane</Street Address I > 
10 <StreetAddress2>Poets R 

Us</StreetAddress2> 

<City>Warren</City 
<State>MA</State> 
<Zip>0181(K/Zip> 
1 5 <Country>US A</Country 

<yCreditCard> 
</Billing> 
</Member> 

Major Objects — Contact : identifies an individual to whom a message may be 
20 sent. A Contact Object contains one or more Contact Method sub-objects (described 
below), each of which identifies a way to reach the individual. Contact and Contact 
Method information may or may not be stored in a member's Address Book (i.e., the a 
collection of a member's Contacts and their associated Contact Methods stored in data- 
base 1 52b). Thus, a Contact Major Object may be created to be stored in an Address 
25 Book, or for one-time use. 

Major Objects — Contact — Fields : The Contact object has the following fields: 








6bject--infdrf&i^icm)^. : w^ 

wm 

: ~rj^ : '-.~~ptr^ 
; : < . ii .i H « 9 r* '■ *i '; 

upaat^;;;^ : m;n^] 
required'onlyiwKfen tfie 1 


wmmm 

fo^y^|^:|^;^^t^ 

ut^e^rernoye^^ 

Coritactp^::3^ ! ;te: ^ 

Ii$ftr|;S 

Supplied^aner?a Cpntadv i 
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Prefix . 
(Optional) 

Indicates the contact's . ; 
preferred title; for exam-" ; 
pje v Mr.,.Ms, Drl ■ * : p 

In - ' > /-I 

Strings ~ s ' ■ '■■ . '■] 

<ffefix>l^.</Pretlx> ? ^ \"'\ 

FirsfName 
Middle Name 
Last Name - ; 

The contact s first, middle 

and last in'aiiiesirfu^^t^^ 
last names ■- are required ^ 

rnfr^l 

Each name field is a 
Sring WiuT'a .32^haN y* 
actep-limifi-u ^-v> -a 

<F : irstNamex> William . ^ ^ .-■ ,-, "l 
</FirstName> 'j; ' .if v % ^V^"""! 
<MiddleNa^i^S:; ^ ■■ - 
</MiddleNarne> ,A. ,^ . ,1,; % 
<I^tName>Shakespeare . ^ -a. , ^ 
^astName>^;>r:v^h^ 

Company vf;"^ 
(Optional) 

IndicatesAe-name ofctherj 
cSmpfafi^ 

witfcwfiich the contact; js^ 

affiliated;Tv:4: ^-^ 


^u^^ttp^cn^ : J 
acter^imit{k 

Ing^Cpmpariy^ 

Titlei; ^r^; : 
(foptlbnal^;^: 

Indicates a~j5b itt\$f 6i> : the 


String wiffia 32rchar^ 
a^teriliiftiSfei ^^^^^iS 

^U^Dir^tor|/TiU^ -^J^Srl 


Table 8: Contact Major Object Fields 

Use of the Command field ensures that the Contact Object will be stored in the 
Address Book of the member with which it is associated. When the Contact Object is 
nested as a sub-object of a Job object (described below), the contact information will 
not be stored in an Address Book. 

The following represents a typical Contact Object (with Contact Method objects 
indicated but not actually specified): 

<Contact> 

Prefix>Mr.</Prefix> 
<FirstName> William <yFirstName> 
<MiddleName>L.<^MiddleName> 
<LastName>Shakespeare</LastName> 
<Company>Globe Theater, Inc.</Company> 
Title>Director</TitIe> 

rContactMethod Objects! 
</Contact> 


Major Objects — Contact — Sub-obiects — Contact Method : as explained above, 
this object specifies the manner in which a member may be contacted. A Contact 
Method sub-object may contain some or all of the following fields: 
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Field. 

Description 

In/Out * 

Allowed Values , , ; 



Identifies this 
Contact Method 

plgect}:-'i-;W 

■.*.-* f . " : V/ 
'■■■"* . "J . 

In oKOyt 

Required based on" tiie logic- . 
for the parent Contact object. 
NOTE: fte^ontaef M€$6d 
p&ject; ddgsfnpt h ave; a Bom- 
raand^fielji;.ra 
within a ppntac^ 
does'havera Cpmniapd^eld^ 



Indicates deliy^: 
eryimetfiojr ffl 1 ! 


Rh^g;:v^ :; t;'.=| V/v' ^: • 

^ninS^cfr^emai j<^r^sporf>; ; | 

C^quLred):;] 

Indicatesjffi^^jf 
tycfeolpKOTi^j 
orfaxer; ^.-^ 


N^^^Jrabe^i^^ 

^Quat^ 


more tfiari^nel>: 
^aett^pe^p^ 

twites 
inH 

liStil 

Uiisi^ecgmt^^OTx^S^ 

qmred:iC.there isjmixe^anXfei:: 

Pge;pf a^ia^ifeuMKiffld 

praipf^thWipSb^'^ 

li^^J^rSXiamp^ 

fiSt ptibnferiumBerj ffie ordifc: 

Mfflirffie jp^lffilal^bfild W " 1$ 

^rjOhil^^^inal^: ' ^ 

i 1 ..- jj -«i ' . ■< . . • '^"i :r .* • ... . : : " ; . . 

-iK 4 :.-.- 
MM© 

~ "*.' - -L; ' '. " : : ^ 
lelepjgpn^|^^ 


Typical phonenumbeilwithi:::; 

dist^eM^^^FS^^ij^ 
2 ; 12^458^fty^en1is5^ 




SB 

enfer?aniidfentiryi5g touEfi^tcSie 



Email address^ 



^En^iIMdffi;L^K^;!^;-::i, 1\ 
^e^!S[e^ATA^ 

fs^Etnai d dressl^^ s^t*- ffi^ 


sit^M^dfSssW 


Sn^SMitKISSIfeharactCT^l^ 

^^tMl^.:R^.^y^^^;|;S 





^n^^^i^rMsftifja^iS^Sil 


StiitemtiniB6rV:if 

^; : v>.->.it:7-.~; : »-LCBr-vR«i«' 


^^^V? '"jEB"S^i^^Sr t j^i^i^i; ^y^^v/'^ r^T^;?^! 

Stragiwithj32[<^ 
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City . 

City - ;;■ 

In 

String with 32 character limit 

<City>^ew York^Cjty> 

State- H 

State f V^ ,T "? 

In : 

Two-ch ^cterfabbrieViation 

<^e>®^§yite>:.. : ;^- '-'^P-'.\ 

Zip - ^ 

Zipicodein tHe : 
US; postal code 
elsewhere; i 


Stringer' |* : " • - A ;K * ; 

i"> ■. . ^ ■•. - / '.-... J .. . jrSU? f*-l'i - : r 

Zi^>10D21^/Zip> 

Country 'V* 

Country r !f? ] 

In 

String|;with 32 character limit ' 

<e:puntry>USA^Coun|ry> : 


Table 9: Contact Method Sub-object Fields 

To denote a member's primary e-mail address, for example, the following syn- 
tax is employed: 

5 <Contact Method> 

<transport>email</transport> 

<qualif]er>member<yqualifier> 

<EmailAddress>ralph@poets.com</EmailAddress> 


10 </Contact Method> 

The following example illustrates addition of a new contact to an Address 

Book: 

<Contact> 

<Command>create</Command> 
15 <FirstName>Albus</FirstName> 

<LastName>Dumbledore</LastName> 

<Company>Hogwarts School for Witchcraft and Wizardry</Company> 
<Title>Headmaster</Title> 


20 <ContactMethod> 

<Transport>phone</Transport> 
<Qualifier>cell</Qualifier> 
<PhoneNum>978555 1 234<VPhoneNum> 
</ContactMethod> 


<ContactMethod> 

<Transport>pager</Transport> 
<PagerNum>888555 1 234</PagerNum> 
<AccessCode>1030#</AccessCode> 
30 </ContactMethod> 


</Contact> 
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Major Objects — Contact — Sub-objects — Contact MethodRef : once a Contact 
Method has been created and stored, it may be referred to using a pointer called a Con- 
tact MethodRef. The pointer contains the Contact Method's Id, or a combination of 
fields that will uniquely identify that Contact Method. 

5 A Contact MethodRef sub-object may contain some or all of the following 

fields: 


Ejeldi; ; "•££ : * f ; 

Description ":" ^ : ! r * =■■ 

[ri/Oiit" 

Allowed yajues- v J;; ;f i 

Exam pje ■ ^ , : - -r * f £ ; fa 


Went ifiesfth is^gontact^ 
Method o&ject^.r 





fro^the Contact; pbK: 


Existing:Cpnfact : fid jj- 

<FiiretN^e>Rori^ 
p^y>Hogw^<^mpMy>|ii:. ;.. v 

Trarispfofft|r ^ 

fhese^fie Ids; ar^a!I:i^5 
Metfioci subnobject 


:,; • > . ... ^slJ-: "-" \v* :> ■* % ^- ■ -Q; 

" i".* -"i? w . .rll^!*^"- ' r ~y ' -M 

<Frp^s^ri^^^^ 

<ordinal^O<0^inafe!;;^ .;-v J 

- : " ji' . tS^V ~:?|?f«* ■ r^W: -I: 




Ifetos.fieldaS*set to;aySlUjev 
the^r^onS^-M^hoS' "I 

i'."--7w ''• r ~ ... * . . i'. j. . M\'\ 

^ili^Multi^ 


Table 10: Contact MethodRef Sub-object Fields 

Major Objects — Distribution List : a Distribution List is a grouping of Contact 
10 Methods. It allows a member to send a message to all of the Contact Methods in that 
list. A Distribution List object may contain some or all of the following fields: 
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Field 

Description 

In/Out 

Allowed Values 

Example 

Command 
(Required) 

Indicates the desired action. Options in- 
clude: 

Create (Create a Distribution List) 
Replace (Replace existing Contact Meth- 
ods in this list with the Contact Methods 
contained in this request) 
Append (Add Contact Methods to the :'.>.- 
existing list) - - * ■ =-*-. : * 
Delete (Delete Contact Methods from the. 

RemoveXRemoye the whole Distribution 'J 

List).;- : : ■ . . .-. V r 

In 

Must include one of 
the following values: 
create 

replace ... 
append :: 
delete : ' 
remove : 

<Cornmand>append 
</Command> w -. i- ; ;; : 

Narne^;- ^1 

Unique v hame'TcV- DistnbutionlListl^ 

In" -S; 

; ■ , . ■ 

When creating a list, 
giye-Jt a unique name; 
forexample, :: r : : 
"Gry^clor^i" ]-Jr 
character limit). , ; 
^TC:;When using]- 
any: other command?; ■ 
option, you musteriter 
eithdr Same or ld v ; : 
field tpiHentify; the. 
Distribution List "]'. -=--."' 

<^ame^G.ry fifindpr^ j 
Name> "'•: : -^i-i'7 V-^":::;^ 

Description 

Descriptive ftext alwutme list . *"^*j~V.^ 


-. c:r=K. :-- /r i3. yi..~ 

Optional field ; : };f t .\ ^ 

- . # .. ■ . i 

<Descrip- ; -: . ; ; ; 
tiori>6ryJfmdpr: >.: ; j 
Ho]ise-^escriptioh> 


Unique identifier for the List 'li '■- .'.-v ^-l^d 

fa/Out \ 

If the valueof the ; : ; 
Command field is ; ^ 
create, no.Id field is 
required; :if any other: : 
value, enter a yalue^..;*; 
or eimerName-otld^J 

fieltf^y^'--; 



Table 11: Distribution List Major Object Fields 

In addition, the Distribution List object must have a list of Contact MethodRef 
sub-objects (i.e., pointers to already-created Contact Method objects). An exemplary 
5 Distribution List object is as follows: 

distribution List> 

<Command>append</Command 
<Name>Gryffindor</Name> 

<ContactMethodRef> 
i o <LastName>Potter</LastName> 
<Transport>email</Transport> 
</ContactMethodRee> 
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<ContactMethodRe£> 
<Id>kkk3btkk</Id> 
</ContactMethodRef> 

</Distribution List> 


10 


Major Objects — Job : a Job object contains a message to one or more Contacts 
using one or more Contact Methods, and contains sub-objects that define the specifics 
of the messaging task (e.g., the sender, the body of the message, recipients, etc.) A Job 
object also contains at least one Message sub-object (described below), and one or 
more Delivery Request or Contact sub-objects. 

A Job object contains only two fields, and these are specified only in a Re- 
sponse: 



Descri p t ion " ^= : igv&gjl n/0u tMS 




fdenti fier fer- this J^iJO u Vi;v^-- 


<Id>k^btkk</I$> , ^ 






15 


Table 12: Job Major Object Fields 

Major Objects — Job — Sub-objects — Message: the Message sub-object speci- 
fies the actual message. It includes fields and optional MessageArg Objects, and al- 
lows the requester to specify delivery times. 




In/Out^ 




Hw!^SuBj^liii'efof#i 



Fnda^g:saies^ggcting 
canc^^]]>^^^iject>S 

Ky ; pl^tf;(ORr ; : 

|^^);fi^; 






lSni<^;id<^if^ 
tnis^Message subrr;fe;rr 
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0ate-4" - ' ...... 

Marks the date and 1- j 
rime the message was 
submitted : ' 



<bate>]999:lX)i20:: \ 

DeliveryTime < 

Marks the reouested ^ : 
time of delivery / • : ; ;;| 


'.' ' ■ ■ * " . i: J. ■ ■ 

<DeIive^^vi-V^ : -..^n- ■ v v- r 
1 9: 1 4:3.9<^e^^^ 

Efeliye^f . 
^ime^tfifierv- 

Options re jaied to; tfiej 
requested delivery time 


-Jx~— 1 7^^. . \riii'?;:kc* •" ; ; • 

StotiS^t^fBi^TbFihishBy; 

<Deliyi^ifimeM 
fi?r>(StiS 

f ime^SaifierS^ *Ml|pfc 


Table 13 
Job Major Object 
Message Sub-object Fields 

Major Objects — Job — Sub-obiects — Message — MessageArg Sub-objects : a 
Message object contains one or more MessageArg sub-objects that consist of a series of 
Name/Value tags according to the following syntax: 


10 


<MessageArg> 

<Name>SENDER</Name> 
<VaIue>Hermione Grainger</V alue> 

</MessageArg> 


The optional MessageArg Name/Value tags are as follows: 


Nfalues^ 


3^e;§ende1^@e^^ 


Gharkcter' 
string; 


1 ber|nahieT tIt|iS^ ^ite 

all njgho^^^^j 
p or^e x^eFjteman^ 


m ^Nanji^SEr^ 


Hieractual textiofethe^ 


5 lit- „4i : i^y^isfci "I i'. ---'■^vS"'' ixn;<is>~- /jis"* Stv"'* 


s'flingS : f# 


^ame>RODY£7N^ 
i^Kaveiseheduled an^ 
withrSi^herin^ 
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^sk^YES^QlJtSTION 

YES ' 

NO . • 

If a ; yes/no question is; 
asked, this should be ^ 
set toi YES, otherwise 
NO;;for example,. 

<MessageArg>J:, L . ; V: 

<Na*ne>ASKi^ ? 

<Value>YES^yalue>^. 

<vMessageArg^; ■ .j .'• y; 

Qiflst^ 

:V\"J 

If the - *■ t\-\ '1 
ASK^YESNC^QUESl 

YES^use thi^'field to i 
enter the: actiialtext of: 

<Messa^Arg>^r^ .--"-*■•»'■:■'; 1 .y^/ ; ^.\J:" J 
<^ame^^QUE^iPN:TO ASK<7Name^V j 

Pan -Vrtii*nijiVft'tKf* nrflrtif''** q^qqiKtWII^ .^ui/'.''^ 



The^Shail address that" 
is use*i in thejFrom jg| 

wh^Sseridifig ja *nesH; J| 
sagi^ia eriiail /jj^i 

<Mes^eAxg>\-~ /t^yv" "pto"'*** 
^arn^mil^DDR^ajne>:- : • 

^aiue^: — ^ /'::ji\ : ' ; ; : ">-;^f7:i 

^^^geArg^.'. ; r-j-Wv^^ 


Table 14 
Job Major Object 
Message Sub-object 
5 MessageArg Sub-object Tags 

An exemplary Job Object is as follows: 

<Job> 

<Message> 

<Subject>Extra Quidditch Practice</Subject> 
10 <TempIate>generic</Template> 

<MessageArg> 
<Name>SENDER</Name> 
<Value>Oliver Wood<WaIue> 
</MessageArg> 

15 <MessageArg> 

<Name>BODY</Name> 
<VaIue><![CDATA[ 

I have scheduled an extra Quidditch practice session before the match with Slytherin. Be 
there Wednesday at 8:00AM sharp. 
20 ]]> 

</Value> 
</MessageArg> 

<MessageArg> 
<Mame>ASK_YESNO_QUESTION</Name> 
25 <Value>YES</Value> 
</MessageArg> 

<MessageArg> 
<Naine><QUESTION_TO_ASK</Name> 
<Value><![CDATA[ 
30 Can you make the practice session?] ]> 
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</Value> 
</MessageArg> 

<MessageArg> 
<Name>EMAlL_ADDR</Name> 
5 <VaIue><![CDATA[ 

wood@H ogwarts .edu) ]> 
</Value> 
</MessageArg> 

</Message> 
10 <Contact> 

<FirstName>HarTy</FirstNaine> 
<LastName>Potter</LastNanie> 
<ContactMethod> 
<Transport>emaiI</Transport> 
1 5 <Emai!Address>potter@hogwarts.edu</EmailAddclress> 
</ContactMethod> 

</Contact> 

<DeliveryRequest> 

<ContactMethodRef> 

20 <LastName>Weasley</LastName> 
<Transport>email</Transport> 

</ContactMethodRe£> 
</DeliveryRequest> 
</Job> 

25 Major Objects — Job — Sub-objects — Delivery Request : the Delivery Request 

sub-object allows the requester to specify a recipient for a job, as well as to specify de- 
livery options (as fields within the sub-object). The Delivery Request Object may 
contain a Contact MethodRef sub-object (to refer to a previously created contact 
method for the recipient) or may instead refer to a Contact sub-object of a Job object 

30 (for one-time use of that Contact/Contact Method). 

An exemplary Delivery Request sub-object is as follows: 

<DeliveryRequest> 

<ContactMethodReO 

<LastName>Potter<yLastNanie> 
35 <Transport>email</Transport> 
<Qua!ifier>home<Qualifier> 

</ContactMethodRef> 
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</DeIiveryRequest> 

The Delivery Request sub-object is also returned by API 145 as a Response. 
Furthermore, when an existing Job object is retrieved using a Range object lookup (de- 
scribed below), that job's Delivery Requests are also returned. 


5 The Delivery Request sub-object may contain the following fields: 




In/Out^ 
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Table 15 
Job Major Object 
Delivery Request Sub-object Fields 


An exemplary Delivery Request Response is as follows: 
<DeliveryRequest> 

<ID>kztubkkkk</ID> 
<EstDuration>80</EstDuration> 
10 <Status>Not Sent</Status> 

<DeliveryOptions>Standard</DeliveryOptions> 

<Completed>false</CornpIeted> 

<ContactMethod> 

<ID>kit5bkJcuk</ID> 
1 5 <Transport>phone</Transport> 
<Qualifier>orTice</Qualifier> 
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<Unreachable>false<AJnreachable> 
<EmaiJAddress>potter@hogwarts.edu</EmailAddress> 

</ContactMethod> 

<Contact> 

5 <ID>kk36bkkkk</ID> 

<Prefix></Prefix> 

<FirstName>Harry</FirstName> 

<MiddleName></MiddleName> 

<LastName>Potter</LastName> 
10 <Company>Hogwarts School for Witchcraft and Wizardry </Company> 

<TitIe>Student</Title> 

<OneTime>true</OneTime> 

<yContact> 
</DeliveryRequest> 


Major Objects — Job — Sub-obiects — Delivery Request — Delivery Sub-object : 
the Delivery sub-object never appears in a Request. It is returned by API 145 as a sub- 
object of a Delivery Request object when a Range object lookup (see below) is per- 
formed on a job. 

20 The Delivery sub-object may contain the following fields: 
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Table 16 
Job Major Object 
Delivery Request Sub-object 
5 Delivery Sub-object Fields 

Major Objects — Range : The Range object facilitates retrieval of a list of ob- 
jects based on specified criteria. In particular, the Range object can retrieve Distribu- 
tion List, Job, and Contact objects. The Response to a Range object returns the re- 
10 quested objects. 

The Range Major Object may contain the following fields: 
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Fields Descripti n |=Iii/Out |aII wed Values 

Example 

Object 

Specifies the type of object you 
are trying to look up 

In 

DistributionList 
Job 

Contact 
Member 

<Object> 

DistributionList 

</Object> 


Specifies criteria forthe lookup; 
depend 6n;the value;o£ <6b-" : 
ject>: ; . z : : ^: SSS.^;^; 
DistributionList^ 

job ;" "-T^r^^fe^S&i 
^ntect v ^ 

iri",::s;:,^ 

If Objects value is Distribu- 
tion List: 

Name (look up by Name fieid) 
Id (lookup by Id field); 
All (return all Dist. Lists for 

th'is-I^ember)vj'-:;:;„^-r'- : : ; ;.'r* 

Date (Ipok upby date) v i 
Id.(iqok up.by Id)\. ; . 
All (return all Jobs for this 

Member)t:>;; J - ^ - . 
e6^tact:'ftj^^^; t ^:r ;:;:>";:-l-. - 

Name fieloO;?:-:;?: ."\ T":;:;:"-""- ^ 
Id;(36ok^ |: U 
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panyVfieldy-- 

All (returrrail Contacts fortnis 
Member); ;; ; • • ; ; ; ;.; ; : . t : 
Meirifen:*^^ 

Username (lookup by User- . 
name, field), 

Id (Ib6kup r by Id field) ;r:' % :^.: 

<Type>Name</rype> iS-^- : S"" 
■;./:: : ;v:: n v; . :;;§;• j 

r iii,r.Vi 
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Table 17 
Range Major Object Fields 


5 The Range object is always included in a Request object, with the value of the 

RequestType set to "lookup." The most common use for the Range object is to look up 
a Job object by Id, for example, 

<Range> 

<Object>job</Object> 
10 <Type>ld</Type> 


WO 01/69385 


PCT/US01/07727 


36 


<Start>kkky5btk</Start> 

<Range> 


Error Handling : Errors fall into three classes: parsing errors, fatal errors, and 
5 errors/warnings encountered while validating any object or field. 

Parsing errors occur when the input XML tags do not conform to XML specifi- 
cations. Typical examples of malformed XML code include tags that are not closed 
and illegal characters; to avoid the latter type of error, free-form text should be en- 
closed within CD ATA tags. When parsing errors are encountered, API 145 returns a 
10 ParseErrors object, which contains one or more sub-objects called ParseError and hav- 
ing the following fields: 



Description 



Eiamiple ■ "jS/ : . "'^ rjr " 


rextexplainiiig^ 

*rt-: ::y ? t .. s A .... . . ( _- -y . v«s -.-rfis 

: » /.it- ;V~ : . : . ; ' " r". 17^ . * * " " : '-?T " ™. ".3*7?^ 



^ETOrSttirig>Exp^tmg 

'aharriey; 

LiiteNumber 

Liin[equj&be£^ 

BP 


^^ineNi^ber>JI - -=7 1 



Table 18 
ParseError Sub-object Fields 

15 

An example is as follows: 
<ParseErrors> 

<ParseEiTor> 

<ErrorString>Expecting 'a name', found *?* /ErrorString> 
20 <LineNumber>9</LineNumber> 
</ParseError> 
</ParseErrors> 


WO 01/69385 


PCT/US01/07727 


37 

A fatal error signifies a significant problem encountered in the course of proc- 
essing a Request. API 145 returns a FatalError object with a single field (ErrorString), 
which indicates the nature of the error. For example, 

<Fata!Error> 

<ErrorString>User Transaction Server UnavaiIabie.</ErrorSiring> 
</FatalError> 


Validation errors and warnings are attached to problematic objects or fields as 
"attributes." The Errors and Warnings fields of a Response object contain the follow- 
ing information: 




In/Out 

Allowed Values' 



wKil^rpces^ 


. ... j-;*^;- si.:;:*;* ,: ;r *;? jr;~: 

linjugrredfu^ 
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Unsigned r integer 4 1 
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Table 19 
Response Super Object 
Errors and Warnings Fields 

For example, if a Request contains an invalid telephone number, a warning at- 
tribute will be attached to the problematic <PhoneNum> field. If a Request fails to 
provide a Billing sub-object when trying to add a Member, an error attribute will be 
attached to the Member object. 

It will therefore be seen that the foregoing represents a full-featured messaging 
system capable of operating in multiple communication modes and interacting with re- 
mote applications through a common, extensible interface. The terms and expressions 
employed herein are used as terms of description and not of limitation, and there is no 
intention, in the use of such terms and expressions, of excluding any equivalents of the 
features shown and described or portions thereof, but it is recognized that various modi 
fications are possible within the scope of the invention claimed. 

What is claimed is: 
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CLAIMS 

1 1. A messaging system comprising: 

2 a. a message server comprising a plurality of modalities for transmitting 

3 messages, the message server being responsive to a remote application config- 

4 ured to generate a message and a designation of at least one of the transmission 

5 modalities, the message server communicating with the application via a com- 

6 puter network; and 

7 b. an application program interface (API) comprising stored instructions 

8 executing on the message server, the API receiving the message and designation 

9 from the application and causing the message server to effect transmission of 

10 the message according to the designation. 

j 2. The system of claim 1 wherein the API is configured to interpret XML 

2 syntax, the message and the designation being expressed as a request formatted in XML 

3 syntax. 

i 3. The system of claim 1 wherein the message server comprises a database 


2 for storing contact data, the API being configured to process a request from the appli- 

3 cation to establish a database record specifying a member and contact data for the 

4 member, the contact data including at least one contact method specifying a transmis- 

5 sion modality and data facilitating contact of the member via the specified transmission 

6 modality, the API causing the message server to send the message in accordance with 

7 the contact data. 

1 4. The system of claim 1 wherein the message server comprises a database 

2 for storing contact data for a plurality of members, the API being configured to process 

3 a request from the application to (i) access an existing database record specifying a 

4 member and contact data for the member, the contact data including at least one contact 

5 method specifying a transmission modality and data facilitating contact of the member 

6 via the specified transmission modality, or (ii) obtain contact data from the application 
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7 for a non-member, the API causing the message server to send the message in accor- 

8 dance with the contact data. 

5. The system of claim 4 wherein the API is further configured to process a 
request from the application to create a distribution list comprising a plurality of the 
existing database records, the API causing the message server to send the message to 
the members in the distribution list in accordance with the contact data. 

6. The system of claim 4 wherein the existing database record comprises a 
plurality of contact methods, the API being further configured to process a request from 
the application specifying at least one of the contact methods, the API causing the mes- 
sage server to send the message to the member in accordance with the at least one 
specified contact method. 

7. The system of claim 1 wherein the API is further configured to respond 
to status requests from the application, the API returning, in response to a status request 
specifying a messaging task, status information pertinent to the messaging task. 

8. The system of claim 7 wherein the status information includes a status 
designation for the message, the status designation specifying (i) whether the message 
has been sent, (ii) whether the message was successfully received, (iii) whether the 
message failed, and (iv) whether the message has been cancelled. 

9. The system of claim 8 wherein, for each failed message, the API returns 
an explanation for the failure. 

10. The system of claim 1 wherein the message is addressed to at least one 
contact, the message comprising a question, the API causing the message server to pose 
the question to the at least one contact. 

1 1 . The system of claim 1 0 wherein the API is further configured to respond 
to status requests from the application, the API returning, in response to a status request 
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specifying the message, status information pertinent to the message including any re- 
sponse to the question by the at least one contact. 

12. The system of claim 1 wherein the API is configured to handle informa- 
tion in the form of objects, the objects including (i) member objects designating mem- 
ber information for a plurality of potential recipients of the message, (ii) contact objects 
specifying information facilitating communication with the potential recipients in ac- 
cordance with a plurality of transmission modalities, (iii) job objects specifying mes- 
sages and characteristics thereof, and (iv) delivery objects specifying modes of message 
delivery, the application providing the message and the designation in object form. 

13. For use in conjunction with a message server comprising a plurality of 
modalities for transmitting messages and an interface for communicating with remote 
applications via a computer network, an application program interface (API) compris- 
ing stored instructions executing on the message server, the API being responsive to 
application-originated requests comprising a message and a designation of at least one 
of the transmission modalities, the API causing the message server to effect transmis- 
sion of the message according to the designation. 

14. The API of claim 1 3 wherein the executing instructions interpret XML 
syntax, the message and the designation being expressed as a request formatted in XML 
syntax. 

15. The API of claim 1 3 wherein the message server comprises a database 
for storing contact data, the API being configured to process a request from the appli- 
cation to establish a database record specifying a member and contact data for the 
member, the contact data including at least one contact method specifying a transmis- 
sion modality and data facilitating contact of the member via the specified transmission 
modality, the API causing the message server to send the message in accordance with 
the contact data. 
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16. The API of claim 13 wherein the message server comprises a database 
for storing contact data for a plurality of members, the API being configured to process 
a request from the application to access an existing database record specifying a mem- 
ber and contact data for the member, the contact data including at least one contact 
method specifying a transmission modality and data facilitating contact of the member 
via the specified transmission modality, the API causing the message server to send the 
message in accordance with the contact data. 

1 7. The API of claim 1 6 wherein the API is further configured to process a 
request from the application to create a distribution list comprising a plurality of the 
existing database records, the API causing the message server to send the message to 
the members in the distribution list in accordance with the contact data. 

1 8. The API of claim 16 wherein the existing database record comprises a 
plurality of contact methods, the API being further configured to process a request from 
the application specifying at least one of the contact methods, the API causing the mes- 
sage server to send the message to the member in accordance with the at least one 
specified contact method. 

19. The API of claim 1 3 wherein the executing constructions are configured 
to respond to status requests from the application, the API returning, in response to a 
status request specifying a messaging task, status information pertinent to the messag- 
ing task. 

20. The API of claim 1 9 wherein the status information includes a status 
designation for the message, the status designation specifying (i) whether the message 
has been sent, (ii) whether the message was successfully received, (iii) whether the 
message failed, and (iv) whether the message has been cancelled. 

21 . The API of claim 20 wherein, for each failed message, the API is con- 
figured to return an explanation for the failure. 
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22. The API of claim 1 3 wherein the message is addressed to at least one 
contact, the message comprising a question, the API causing the message server to pose 
the question to the at least one contact. 

23. The API of claim 22 wherein the executing instructions are configured 
to respond to status requests from the application, the API returning, in response to a 
status request specifying the message, status information pertinent to the message in- 
cluding any response to the question by the at least one contact. 

24. The API of claim 13 wherein the executing instructions are configured 
to handle information in the form of objects, the objects including (i) member objects 
designating member information for a plurality of potential recipients of the message, 
(ii) contact objects specifying information facilitating communication with the potential 
recipients in accordance with a plurality of transmission modalities, (iii) job objects 
specifying messages and characteristics thereof, and (iv) delivery objects specifying 
modes of message delivery, the application providing the message and the designation 
in object form. 

25. A method of handling and transmitting messages to recipients, the 
method comprising the steps of: 

providing a message server comprising a plurality of modalities for transmitting 
messages, the message server being responsive to a remote application configured to 
generate a message and a designation of at least one of the transmission modalities; 

causing the message server to communicate with the application via a computer 
network; and 

c. providing an application program interface (API) comprising stored instruc- 
tions executing on the message server, the API receiving the message and designation 
from the application and causing the message server to effect transmission of the mes- 
sage according to the designation. 
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26. The method of claim 25 wherein the API is configured to interpret XML 
syntax, the message and the designation being expressed as a request formatted in XML 
syntax. 

27. The method of claim 25 further comprising the step of providing a data- 
base for storing contact data, the server processing a request from the application to 
establish a database record specifying a member and contact data for the member, the 
contact data including at least one contact method specifying a transmission modality 
and data facilitating contact of the member via the specified transmission modality, the 
server sending the message in accordance with the contact data. 

28. The method of claim 25 further comprising the step of providing a data- 
base for storing contact data for a plurality of members, the server processing a request 
from the application to access an existing database record specifying a member and 
contact data for the member, the contact data including at least one contact method 
specifying a transmission modality and data facilitating contact of the member via the 
specified transmission modality, the server sending the message in accordance with the 
contact data. 

29. The method of claim 28 further comprising the steps of (i) processing a 
request from the application to create a distribution list comprising a plurality of the 
existing database records, and (ii) sending the message to the members in the distribu- 
tion list in accordance with the contact data. 

30. The method of claim 28 wherein the existing database record comprises 
a plurality of contact methods, the request from the application specifying at least one 
of the contact methods, the message server sending the message to the member in ac- 
cordance with the at least one specified contact method. 

3 1 . The method of claim 25 further comprising the step of responding to 
status requests from the application, the server returning, in response to a status request 
specifying a messaging task, status information pertinent to the messaging task. 
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32. The method of claim 32 wherein the status information includes a status 
designation for the message, the status designation specifying (i) whether the message 
has been sent, (ii) whether the message was successfully received, (iii) whether the 
message failed, and (iv) whether the message has been cancelled. 

33. The method of claim 32 wherein, for each failed message, the server re- 
turns an explanation for the failure. 

34. The method of claim 25 wherein the message is addressed to at least one 
contact, the message comprising a question, the message server posing the question to 
the at least one contact. 

35. The method of claim 34 wherein server responds to status requests from 
the application, the server returning, in response to a status request specifying the mes- 
sage, status information pertinent to the message including any response to the question 
by the at least one contact. 

36. The method of claim 25 wherein the API is configured to handle infor- 
mation in the form of objects, the objects including (i) member objects designating 
member information for a plurality of potential recipients of the message, (ii) contact 
objects specifying information facilitating communication with the potential recipients 
in accordance with a plurality of transmission modalities, (iii) job objects specifying 
messages and characteristics thereof, and (iv) delivery objects specifying modes of 
message delivery, the application providing the message and the designation in object 
form. 
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